package com.sinai.mshab.client.ui.pages;

/**
 * <code>SidePanel</code>s are containers for {@link SidePanelItem}s.
 * <code>SidePanel</code>s are used in the west, north, east, and south
 * sections of a {@link PageContainer}.
 * 
 * @author Arthur Kalmenson
 */
public interface SidePanel {

	/**
	 * Adds a {@link SidePanelItem} to this panel.
	 * 
	 * @param item
	 *            new item to add.
	 */
	public void add(SidePanelItem item);

	/**
	 * Returns the {@link SidePanelItem} with the unique identifier
	 * <code>id</code>. If no such item exists, null will be returned.
	 * 
	 * @param id
	 *            the unique identifier of the {@link SidePanelItem} we want.
	 * @return the {@link SidePanelItem} with the unique identifier
	 *         <code>id</code> and null otherwise.
	 */
	public SidePanelItem get(String id);

	/**
	 * Removes the {@link SidePanelItem} who's id matches <code>id</code> and
	 * returns the index where it was removed. If no such item exists, -1 will
	 * be removed.
	 * 
	 * @param id
	 *            the unique identifier of the item to remove.
	 * @return the index of the item removed, or -1 if no such item exists.
	 */
	public int remove(String id);
	
	/**
	 * Clears this <code>SidePanel</code>.
	 */
	public void clear();

	/**
	 * Returns the number of items in this <code>SidePanel</code>.
	 * 
	 * @return the number of items in this <code>SidePanel</code>.
	 */
	public int size();

	/**
	 * Returns true if this <code>SidePanel</code> is empty and false
	 * otherwise.
	 * 
	 * @return true if this <code>SidePanel</code> is empty and false
	 *         otherwise.
	 */
	public boolean isEmpty();
}
